cfInterval - ColdFusion Intervals/Ranges/Timespan's that don't suck.

Human friendly helpers for working with intervals / timespans. Built on top of a port of the JavaScript TimeSpan library (Timespan.js), inspired by .net's System.TimeSpan and System.DateTime

• cfInterval - ColdFusion Intervals/Ranges/Timespan's that don't suck.
  • CREATING THE OBJECT
    • 1. Using the new constructor
    • 2. Using the static constuctors
  • ADDING/SUBTRACTING TIME
  • INTERACTING WITH OTHER TIMESPANS
  • RETRIEVING THE VALUE OF THE TIMESPAN
  • MISC. FUNCTIONS
  • Prior Art & Inspiration

CREATING THE OBJECT

You have two options to create a new TimeSpan object:

1. Using the new constructor

var ts = new TimeSpan();

The constructor takes five parameters, all of which are optional and which can be used to initialize the TimeSpan to a given value. These parameters are:

milliseconds;
seconds;
minutes;
hours;
days;

Example:

var ts = new TimeSpan(0, 16, 4);

initializes the TimeSpan to 4 minutes, 16 seconds and 0 milliseconds.

var ts = new TimeSpan(0, 10, 64, 2);

initializes the TimeSpan to 3 hours, 4 minutes, 10 seconds and 0 milliseconds.

2. Using the static constuctors

You can initialize a new TimeSpan by calling one of these functions:

TimeSpan.FromSeconds;
TimeSpan.FromMinutes;
TimeSpan.FromHours;
TimeSpan.FromDays;
TimeSpan.FromDates; // this behaves differently, see below

these take a single numeric parameter and create a new TimeSpan.

var ts = TimeSpan.FromSeconds(45);

is equivalent to

var ts = new TimeSpan(0, 45);

If the parameter is invalid/not a number, it will just be treated as 0 but not throw any error.

TimeSpan.FromDates;

This is different as it takes two dates. The TimeSpan will be the difference between these dates.

If the second date is earlier than the first date, the TimeSpan will have a negative value. You can pass in true as the third parameter to force the TimeSpan to be positive always.

Example:

var date1 = new Date(2010, 3, 1, 10, 10, 5, 0);
var date2 = new Date(2010, 3, 1, 10, 10, 10, 0);
var ts = TimeSpan.FromDates(date2, date1);
var ts2 = TimeSpan.FromDates(date2, date1, true);
alert(ts.totalSeconds()); // -5, because we put the later date first
alert(ts2.totalSeconds()); // 5, because we passed true as third parameter

ADDING/SUBTRACTING TIME

There are several functions to add or subtract time:

addMilliseconds;
addSeconds;
addMinutes;
addHours;
addDays;
subtractMilliseconds;
subtractSeconds;
subtractMinutes;
subtractHours;
subtractDays;

All these functions take a single numeric parameter. If the parameter is invalid/not a number/missing, it will be ignored. No error is thrown.

var ts = new TimeSpan();
ts.addSeconds(30);
ts.addMinutes(2);
ts.subtractSeconds(60);
// ts will now be a timespan of 1 minute and 30 seconds

The parameter can be negative to negate the operation:

ts.addSeconds(-30);

is equivalent to

ts.subtractSeconds(30);

INTERACTING WITH OTHER TIMESPANS

These are the functions that interact with another TimeSpan:

add;
subtract;
equals;

To add/subtract the other TimeSpan to the current one:

var ts = TimeSpan.FromSeconds(30);
var ts2 = TimeSpan.FromMinutes(2);
ts.add(ts2);
// ts is now a TimeSpan of 2 Minutes, 30 Seconds
// ts2 is unchanged

To check if two TimeSpans have the same value:

var ts = TimeSpan.FromSeconds(30);
var ts2 = TimeSpan.FromSeconds(30);
var eq = ts.equals(ts2); // true
ts2.addSeconds(1);
var eq2 = ts.equals(ts2); // false

RETRIEVING THE VALUE OF THE TIMESPAN

There are two sets of functions to get the value of the TimeSpan:

1. Retrieve the full value

---

totalMilliseconds;
totalSeconds;
totalMinutes;
totalHours;
totalDays;

These functions convert the value to the given format and return it. The result can be a floating point number. These functions take a single parameter roundDown which can be set to true to round the value down to an Integer.

Example:

var ts = TimeSpan.FromSeconds(90);
alert(ts.totalMilliseconds()); // 90000
alert(ts.totalSeconds()); // 90
alert(ts.totalMinutes()); // 1.5
alert(ts.totalMinutes(true)); // 1

2. Retrieve a component of the TimeSpan

---

milliseconds;
seconds;
minutes;
hours;
days;

These functions return a component of the TimeSpan that could be used to represent a clock. For example:

var ts = TimeSpan.FromSeconds(90);
alert(ts.seconds()); // 30
alert(ts.minutes()); // 1

Basically these values never overflow - seconds will only return 0 to 59, hours only 0 to 23 etc. days can grow infinitely. All of these functions automatically round down the result:

var ts = TimeSpan.FromDays(2);
ts.addHours(12);
alert(ts.days()); // 2
alert(ts.hours()); // 12

MISC. FUNCTIONS

getVersion;

Returns the Version of TimeSpan as a string.

Prior Art & Inspiration

• TimeSpan.js